# Office 365 Login
# Table of Contents
# Overview
Users can sign in to ContactManager with their Microsoft 365 account instead of a ContactManager user name and password. Sign-in is matched on the account's user principal name, falling back to its e-mail address, against the users in ContactManager.
Epona hosts an app registration for ContactManager that is used by default, so a customer does not have to register an application of their own. A customer that wants sign-in to run entirely within their own tenant can register the application there instead and enter its ID in the configuration.
# Setup
# Registering the app in Microsoft Entra ID
Only needed when the customer uses their own app registration. Create a new app registration in the Microsoft Entra ID admin center (App registrations → New registration) and give it a recognisable name.
# Account types
Choose which accounts may sign in:
| Option | Who can authenticate |
|---|---|
| This tenant only | Accounts known in the customer's own tenant |
| Any tenant | Accounts from any organisation |
| Any tenant and personal accounts | Also personal Microsoft accounts, for example name@outlook.com |
# Redirect URI
Every ContactManager environment that uses the app registration needs its own redirect URI. Set the platform to Public client (mobile & desktop) and add the authorize address of the installation:
https://someinstallation.eponalegal.com/Login.aspx/Authorize
Replace the host with the URL of the installation in question.
# Permissions
Add the delegated Microsoft Graph permission User.Read. ContactManager uses it to read the profile of the signing-in user, nothing more.
# Implicit grant
Enable the implicit grant flow for access tokens and ID tokens, so the sign-in returns a token directly.
Keep the app registration open — the client ID and tenant ID are needed in the next step.
# Configuring ContactManager
Open the CRM Configuration screen and go to the General section. Four settings control the Office 365 sign-in; they are described in the Configuration Reference.
The client ID is on the app registration's overview page:
For the tenant, the domain name of the tenant may be entered instead of the tenant ID:
# Signing in
# From the website
With Office 365 sign-in enabled, the login page shows an extra button for signing in with a Microsoft account.
The button leads to the Microsoft sign-in page of the configured tenant. After signing in there, ContactManager looks up the user:
| Situation | Result |
|---|---|
| A matching, enabled user exists | The user is signed in |
| A matching user exists but is disabled | A message that the account still has to be activated |
| No matching user, and registration is off | A message that the account was not found |
| No matching user, and registration is on | A new, disabled account is created — see New users |
| Microsoft does not accept the token | The sign-in is refused |
# From the API
A caller that signs in to the API supplies a user name and a password. With Office 365 sign-in enabled, the user's e-mail address may be used as the user name and a Microsoft access token as the password. ContactManager validates the token and signs the matching user in. See API (REST and SOAP) for the login calls themselves.
# New users
When EnableOffice365AccountRegistration is on and someone signs in with a Microsoft account that has no ContactManager user yet, an account is created from their Microsoft profile (name, surname, e-mail address). The new account is disabled, and a notification e-mail is sent to the data manager address configured in the General section, so an administrator can complete and enable it.
The account is created for Windows authentication when a Windows domain name is configured in the General section, and for forms authentication otherwise.
# Configuration Reference
Settings in the General section of the CRM Configuration screen.
# EnableOffice365Login
Enables signing in with a Microsoft 365 account. When off, the Microsoft sign-in button is hidden.
- Allowed values:
true,false - Default:
false
# EnableOffice365AccountRegistration
Creates a disabled ContactManager account for a Microsoft account that authenticated successfully but has no user yet, and notifies the data manager.
- Allowed values:
true,false - Default:
false
# Office365ClientId
Application (client) ID of the app registration used for sign-in.
- Default:
abcac0c1-7028-44d0-b3de-a93362fb0072— the app registration Epona hosts for ContactManager. Replace it with the customer's own client ID when they registered the application in their own tenant.
# Office365AdditionalAllowedClientIds
Extra client IDs whose tokens are also accepted at sign-in. Separate multiple IDs with a semicolon
or a comma. Add abcac0c1-7028-44d0-b3de-a93362fb0072 to keep accepting tokens from the Epona
multi-tenant app that applications such as LegalWord use, when Office365ClientId has been
changed to the customer's own app registration.
- Default: empty
# Office365TenantId
The tenant to authenticate against. Either the tenant (directory) ID or the tenant's domain name.
Leave empty, or use common, to accept accounts from any tenant — not recommended, because that
allows any known Microsoft account to attempt a sign-in.
- Default: empty